Netzwerk Devices

In vielen interaktiven Theatersituationen wollen wir externe Dinge an adaptor:ex anschließen.

Wenn wir, zum Beispiel, ein interaktives Requisit wie die Bombe aus dem machina ex Stück '15 000 Gray' ansteuern wollen, müssen wir ihr Signale im HTTP Protokoll schicken...

In dem folgenden Step by Step Tutorial gehen wir davon aus, dass wir mit einem Device mit HTTP Schnittstelle kommunizieren wollen, aber adaptor:ex unterstützt natürlich auch andere Netzwerkprotokolle (TCP, UDP, UDP/OSC) als auch die Serielle (USB) Schnittstellen (vorausgesetzt wir arbeiten in adaptor:ex im Local Mode).

HTTP Requests schicken

Nachdem wir unser Game ausgewählt oder erstellt haben, wählen wir Game > Settings aus
In den Settings klicken wir auf Devices und dort unter HTTP auf den Plus Button, um ein neues HTTP Device zu erstellen.

Devices existieren auf Game Ebene, also ein und dasselbe Device ist erreichbar aus jedem Level innerhalb eines Games.
Das neue Device bekommt einen Namen. In unserem Beispiel nennen wir es einfach "Bombe".

Unter diesem Namen wird es im Level Editor auffindbar sein, sowohl als Device als auch als Event Quelle (dazu spaeter mehr)
Unter Settings wählen wir nun "to Device" aus, denn wir wollen ja etwas an das Device Bombe schicken.
Hier gibt es potenziell mehr einzustellen. Aber wir halten es erst einmal simpel und füllen nur das Feld URL aus. Das ist die URL (z.B. http://192.168.178.4:3000) der Bombe in unserem Netzwerk.

Dann klicken wir SAVE.

Weil wir die Bombe in unserem internen Netzwerk übers WLAN erreichen können, ist die URL in unserem Fall http:// plus die IP Adresse der Bombe plus :3000 weil unsere Bombe auf Port 3000 hört. Aber würde die Bombe könnte natürlich auch ein Device hinter einer domain sein (z.B. wenn sie über einen Internetservice angesteuert würde oder anderweitig DNS Auflösung stattfindet)

Nun erstellen wir ein Level oder wechseln in das Level aus dem wir unsere Bombe ansprechen wollen (GAME > OVERVIEW > LEVEL auswählen oder erstellen).
Im Level Editor finden wir nun links in der Action Bar, den Bereich "DEVICES" und die Action "Send Message".
Wir ziehen die Send Message Action auf unsere Bühne um einen neuen State mit der Send Message Action zu erstellen.
Wir nennen den State um (z.B. in TRIGGER_BOMB weil wir die Bombe starten wollen) und wählen unter "to" im Action Formular das Device "Bombe" aus, wenn es nicht schon ausgewählt ist.
Wir wissen aus der Dokumentation unseres Bomben Requisits, dass die Bombe gestartet werden kann mit einem GET Request an den endpoint/pfad /AN.

Also schauen wir uns unter Settings an, welche weiteren Felder wir in der Send Message Action auswählen könnten:

message ist die message die wir dem Device schicken wollen. Die Message wird in dem HTTP Request als sogenannte query parameter verschickt. Das brauchen wir im Fall der Bombe noch nicht, ist aber gut zu wissen.

method bestimmt welche HTTP methode angewandt wird. Wenn wir hier nichts angeben (und in den Settings nichts anderes eingestellt ist), wird ein HTTP GET Request versendet. Weil unsere Bombe ausschließlich auf GET Requests hört, brauchen wir das hier also nicht. Aber auch gut zu wissen.

path ist der path an den der HTTP Request geschickt wird. Aha! Die Bombe wird gestartet mit einer Nachricht an /AN. Also wählen wir path aus und schreiben /AN rein.

Die send message Action schickt also, wenn wir in diesem State im Level ankommen, einen HTTP GET Request an die url der Bombe (http://192.168.178.4:3000 wie wir in Step 5. bestimmt haben) und fügt noch den Pfad /AN an die url an (also geht unsere Nachricht an http://192.168.178.4:3000/AN in unserem Beispiel)

Wir verbinden also unseren neuen State (fügen natürlich noch eine NEXT Action ein, etc.), klicken oben rechts auf den LIVE MODUS Button und starten eine Session. Sobald die Session bei unserem State TRIGGER_BOMB ankommt, wird unsere send message Action aktiviert und wir schicken ein HTTP GET Request an unsere Bombe und starten sie.

Huch! Es tickt! Jetzt aber schnell!!!

Perfekt. Wir wissen jetzt also wie wir ein neues Device erstellen und ihm HTTP requests senden! Hervorragend!

Aber was, wenn wir ein Device haben, dass unserem adaptor:ex server/computer HTTP requests senden soll?

HTTP Requests empfangen - mit Webhooks

Unser Beispielrequisit, die Zeitbombe aus 15'000 Gray, schickt im Fall dass ihr Timer abgelaufen ist (Bumm!) als auch in dem Fall dass sie vom Publikum erfolgreich entschärft wurde (Phew!) einen HTTP GET REQUEST an die IP Adresse des Computers auf dem adaptor:ex läuft.

Damit adaptor:ex auf diese Nachrichten reagiert, müssen wir zurück die Game Settings:

Dort wählen wir den Settings Button des Devices Bombe aus und sehen dass es neben to_device auch from-device gibt. Das wählen wir aus.
Weil wir von der Bombe GET requests erwarten, ändern wir nichts, sondern klicken einmal auf SAVE und dann auf den Reload Button oben rechts (das Zirkel Symbol)

Nach einem kurzen Reload sollte nun der Indikator grün leuchten und wir sehen eine URL im Feld webhook. An diese URL sollte nun unsere Bombe ihre Signale schicken.
Wir konfigurieren unsere Bombe (oder jedes andere Device) also so dass es an unsere webhook Adresse schickt. In unserem Beispiel schickt die Bombe nun einen HTTP GET Request mit dem query parameter ?timeout=true wenn sie explodiert oder ?solved=true wenn sie entschärft wurde.

Wir wollen also nun auf diese beiden Events reagieren.
Wir wechseln zurück in den Level Editor und ziehen eine ON EVENT ACTION auf die Stage
Unter Settings fügen wir die from Option hinzu und wählen das http device Bombe im drop down Menü unter Select Source aus. Als event geben wir "incomingMessage" an. Wir wollen also, dass etwas passiert, wenn beim Netzwerk Device Bombe ein incomingMessage Event eintritt.
Der Einfachheit halber wählen wir erst einmal die else Option in den Settings an und verknüpfen diese Listener Action nun mit QUIT
Wenn die Bombe jetzt also einen HTTP GET request an ihren webhook schickt, wird das Event ausgelöst und wir gelangen am Ende des Levels an.

Filter incoming HTTP REQUESTS

Aber wie unterscheiden wir jetzt zwischen einem request mit ?timeout=true und einem mit ?solved=true?

statt wie in Schritt 5. else wählen wir if in den action Settings aus. Die url queries fallen direkt in das Event rein. So können wir die einzelnen queries (timeout und solved) direkt von adaptor:ex anschauen und überprüfen lassen um dann zu bestimmen welcher State in welchem Fall ausgelöst werden darf.

Wir fügen also eine condition hinzu (Add condition) und tragen in das Feld field ein nach welchem query adaptor:ex suchen soll (timeout oder solved) und welchen Wert dieser query parameter haben muss damit etwas passiert (true in unserem Beispiel).

Schließlich tragen wir unter next state den Namen des states ein, der eintreten soll, wenn dies der Fall ist.

Nachdem wir dann noch einen WIN State angelegt haben (der könnte später zum Beispiel Die Siegesmusik abspielen oder Licht ansteuern etc.),sieht das Level jetzt ungefähr so aus:

Und wenn wir in den Live Modus wechseln und eine neue Session starten und diese dann markieren, sehen wir: Die Session bleibt bei dem State ON_BOOM stehen und wartet auf die von uns definierten Events.

Wenn das Bomben Requisit jetzt einen HTTP GET Request an unseren webhook schickt und ?solved=true mit schickt, sehen wir wie der WIN State ausgelöst wird.

Es gibt noch mehr Möglichkeiten den Inhalt des Bombe Events auszulesen (z.b. finden wir die Daten des onEvents auch in der ACTION BAR unter Variables und können ihn dort dann weiter bearbeiten etc.)

So können wir jetzt unsere Requisiten mit adaptor:ex reden lassen als auch von adaptor:ex Signale an externe Devices schicken.

Natürlich lassen sich so auch andere Software im Netzwerk und auf demselben Computer ansteuern und sogar 3rd party Dienste im Netz (obwohl wir für letzteres meistens empfehlen, lieber einen eigenen Plugin zu programmieren, wenn das möglich ist)